﻿using System;

namespace NodeJS
{
    using NodeJS.url;

    /// <summary>
    /// This module has utilities for URL resolution and parsing. Call require('url') to use it.
    /// </summary>
    public abstract class Url
    {
        /// <summary>
        /// Take a URL string, and return an object.
        /// </summary>
        /// <param name="urlStr"></param>
        /// <param name="parseQueryString">Pass true as the second argument to also parse the query string using the querystring module. Defaults to false.</param>
        /// <param name="slashesDenoteHost">Pass true as the third argument to treat //foo/bar as { host: 'foo', pathname: '/bar' } rather than { pathname: '//foo/bar' }. Defaults to false.</param>
        /// <returns></returns>
        public abstract UrlObject Parse(string urlStr, bool parseQueryString = false, bool slashesDenoteHost = false);

        /// <summary>
        /// Take a parsed URL object, and return a formatted URL string.
        /// </summary>
        /// <param name="urlObj">
        /// <para>href will be ignored.</para>
        /// <para>protocol is treated the same with or without the trailing : (colon).
        /// The protocols http, https, ftp, gopher, file will be postfixed with :// (colon-slash-slash).
        /// All other protocols mailto, xmpp, aim, sftp, foo, etc will be postfixed with : (colon)</para>
        /// <para>auth will be used if present.</para>
        /// <para>hostname will only be used if host is absent.</para>
        /// <para>port will only be used if host is absent.</para>
        /// <para>host will be used in place of hostname and port</para>
        /// <para>pathname is treated the same with or without the leading / (slash)</para>
        /// <para>search will be used in place of query</para>
        /// <para>query (object; see querystring) will only be used if search is absent.</para>
        /// <para>search is treated the same with or without the leading ? (question mark)</para>
        /// <para>hash is treated the same with or without the leading # (pound sign, anchor)</para>
        /// </param>
        /// <returns></returns>
        public abstract string Format(UrlObject urlObj);        

        /// <summary>
        /// Take a base URL, and a href URL, and resolve them as a browser would for an anchor tag. Examples:
        /// <para>url.resolve('/one/two/three', 'four')         // '/one/two/four'</para>
        /// <para>url.resolve('http://example.com/', '/one')    // 'http://example.com/one'</para>
        /// <para>url.resolve('http://example.com/one', '/two') // 'http://example.com/two'</para>
        /// </summary>
        /// <param name="from"></param>
        /// <param name="to"></param>
        /// <returns></returns>
        public abstract string Resolve(string from, string to);
    }
}
